The HistoryQuery object contains the following methods:
Note: Some of the examples in this topic use the WScript.Sleep statement, which is not recommended for use when scripting in CygNet Studio. Use TheView EventTimer instead.
The CancelHistoryFiltering method cancels the filtering of history.
CancelHistoryFiltering(TimeToWaitInSeconds As Integer)
| Parameter | Required | Description |
|---|---|---|
|
TimeToWaitInSeconds |
Yes |
The number of seconds to wait for the history query to terminate. This value must be within the range [1 - 100]. |
Example
The following example cleans up the query after it is finished, by clearing the results, canceling the filtering, and destroying the filter.
|
Sub
' history query is finished HistoryQuery.CancelHistoryFiltering()
End Sub |
The CreateHistoryFilter method creates a new history filter thread.
CreateHistoryFilter() As Boolean
Example
The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.
|
Sub
'-----------------SETUP------------------
' create the filter Dim bCreatedOk bCreatedOk = HistoryQuery.CreateHistoryFilter()
' check that the filter thread is running Dim bIsRunning bIsRunning = HistoryQuery.IsHistoryFilterRunning()
'-----------------EXECUTION------------------
' start filtering HistoryQuery.StartHistoryFiltering()
' wait for the thread to obtain history entries WScript.Sleep(1000)
Dim strTag strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
Dim MyDateS MyDateS = "1/7/2010" Dim startDate startDate = CDate(MyDateS) Dim MyDateE MyDateE = "6/4/2010" Dim endDate endDate = CDate(MyDateE)
' retrieve a single history entry Dim pvHistoryInfoXml, bEntryRetrieved pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml) MsgBox pvHistoryInfoXml
' populate the internal set of entries for a given time window Dim nSize, bWindowRetrieved nSize = 0 bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
' iterate through the set and retrieve each individual entry Dim iEntry For iEntry = 1 To nSize pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml) If bEntryRetrieved Then MsgBox pvHistoryInfoXml End if Next
'-----------------RESULTS------------------
' cancel the filtering, and wait 5 seconds for the thread to terminate HistoryQuery.CancelHistoryFiltering(5)
End Sub |
The GetHistoryEntriesWithinWindow method retrieves all of the filtered history entries for the specified tag within the specified time window.
GetHistoryEntriesWithinWindow(Tag as String, StartTime As Date, EndTime As Date, Size As Integer) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
Tag |
Yes |
The point tag for the history entries to be retrieved |
|
StartTime |
Yes |
The earliest date/time of history entries to be retrieved. Note that this value can either be a string in the machine-chosen date/time format (i.e. 'MM/DD/YY hh:mm:ss' for a machine using the American date/time format), or it can be a Date returned from the CDate function. |
|
EndTime |
Yes |
The latest date/time of history entries to be retrieved. Note that this value can either be a string in the machine-chosen date/time format (i.e. 'MM/DD/YY hh:mm:ss' for a machine using the American date/time format), or it can be a Date returned from the CDate function. |
|
Size |
Yes |
The size of the list of history entries returned by this method. |
This method does not actually return a set of history entries. Rather, it populates an internal set of history entries, which can be accessed via GetHistoryEntryFromWindowAsXml.
Example
The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.
|
Sub
'-----------------SETUP------------------
' create the filter Dim bCreatedOk bCreatedOk = HistoryQuery.CreateHistoryFilter()
' check that the filter thread is running Dim bIsRunning bIsRunning = HistoryQuery.IsHistoryFilterRunning()
'-----------------EXECUTION------------------
' start filtering HistoryQuery.StartHistoryFiltering()
' wait for the thread to obtain history entries WScript.Sleep(1000)
Dim strTag strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
Dim MyDateS MyDateS = "1/7/2010" Dim startDate startDate = CDate(MyDateS) Dim MyDateE MyDateE = "6/4/2010" Dim endDate endDate = CDate(MyDateE)
' retrieve a single history entry Dim pvHistoryInfoXml, bEntryRetrieved pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml) MsgBox pvHistoryInfoXml
' populate the internal set of entries for a given time window Dim nSize, bWindowRetrieved nSize = 0 bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
' iterate through the set and retrieve each individual entry Dim iEntry For iEntry = 1 To nSize pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml) If bEntryRetrieved Then MsgBox pvHistoryInfoXml End if Next
'-----------------RESULTS------------------
' cancel the filtering, and wait 5 seconds for the thread to terminate HistoryQuery.CancelHistoryFiltering(5)
End Sub |
The GetHistoryEntryAsXml method retrieves a single history entry for the specific tag and date.
GetHistoryEntryAsXml(Tag as String, StartTime As Date, HistoryInfoXml As Variant) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
Tag |
Yes |
The point tag for the history entries to be retrieved |
|
StartTime |
Yes |
The date/time of the history entry to be retrieved. Note that this value can either be a string in the machine-chosen date/time format (i.e. 'MM/DD/YY hh:mm:ss' for a machine using the American date/time format), or it can be a Date returned from the CDate function. |
|
HistoryInfoXml |
Yes |
The XML representation of the history entry returned by this method. |
Example
The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.
|
Sub
'-----------------SETUP------------------
' create the filter Dim bCreatedOk bCreatedOk = HistoryQuery.CreateHistoryFilter()
' check that the filter thread is running Dim bIsRunning bIsRunning = HistoryQuery.IsHistoryFilterRunning()
'-----------------EXECUTION------------------
' start filtering HistoryQuery.StartHistoryFiltering()
' wait for the thread to obtain history entries WScript.Sleep(1000)
Dim strTag strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
Dim MyDateS MyDateS = "1/7/2010" Dim startDate startDate = CDate(MyDateS) Dim MyDateE MyDateE = "6/4/2010" Dim endDate endDate = CDate(MyDateE)
' retrieve a single history entry Dim pvHistoryInfoXml, bEntryRetrieved pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml) MsgBox pvHistoryInfoXml
' populate the internal set of entries for a given time window Dim nSize, bWindowRetrieved nSize = 0 bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
' iterate through the set and retrieve each individual entry Dim iEntry For iEntry = 1 To nSize pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml) If bEntryRetrieved Then MsgBox pvHistoryInfoXml End if Next
'-----------------RESULTS------------------
' cancel the filtering, and wait 5 seconds for the thread to terminate HistoryQuery.CancelHistoryFiltering(5)
End Sub |
The GetHistoryEntryFromWindowAsXml method retrieves a history entry from the set of entries populated by GetHistoryEntriesWithinWindow.
GetHistoryEntryFromWindowAsXml(EntryNumber As Integer, HistoryInfoXml As Variant) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
EntryNumber |
Yes |
The index of a history entry in the set populated by GetHistoryEntriesWithinWindow. |
|
HistoryInfoXml |
Yes |
The XML representation of the history entry returned by this method. |
This method is designed to be used in conjunction with GetHistoryEntriesWithinWindow, which populates an internal set of history entries, from which one can be retrieved using GetHistoryEntryFromWindowAsXml (this method).
Example
The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.
|
Sub
'-----------------SETUP------------------
' create the filter Dim bCreatedOk bCreatedOk = HistoryQuery.CreateHistoryFilter()
' check that the filter thread is running Dim bIsRunning bIsRunning = HistoryQuery.IsHistoryFilterRunning()
'-----------------EXECUTION------------------
' start filtering HistoryQuery.StartHistoryFiltering()
' wait for the thread to obtain history entries WScript.Sleep(1000)
Dim strTag strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
Dim MyDateS MyDateS = "1/7/2010" Dim startDate startDate = CDate(MyDateS) Dim MyDateE MyDateE = "6/4/2010" Dim endDate endDate = CDate(MyDateE)
' retrieve a single history entry Dim pvHistoryInfoXml, bEntryRetrieved pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml) MsgBox pvHistoryInfoXml
' populate the internal set of entries for a given time window Dim nSize, bWindowRetrieved nSize = 0 bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
' iterate through the set and retrieve each individual entry Dim iEntry For iEntry = 1 To nSize pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml) If bEntryRetrieved Then MsgBox pvHistoryInfoXml End if Next
'-----------------RESULTS------------------
' cancel the filtering, and wait 5 seconds for the thread to terminate HistoryQuery.CancelHistoryFiltering(5)
End Sub |
The IsHistoryFilterRunning method returns true if the history query thread is running.
IsHistoryFilterRunning() As Boolean
The history query thread is executed after a history filter is created; therefore, after a history filter is created, this method will only return false if the filter has been destroyed using CancelHistoryFiltering. Note that this method is checking that the thread is running, not that it is actually performing filtering.
Example
The following example creates a history filter, checks that it is running, cancels it, and checks that it is no longer running.
|
Sub
Dim bCreatedOk bCreatedOk = HistoryQuery.CreateHistoryFilter()
Dim bRunning bRunning = HistoryQuery.IsHistoryFilterRunning()
MsgBox bRunning 'should be "True"
HistoryQuery.CancelHistoryFiltering(100)
bRunning = HistoryQuery.IsHistoryFilterRunning()
MsgBox bRunning 'should be "False"
End Sub |
The StartHistoryFiltering method initiates history filtering on the background thread.
StartHistoryFiltering() As Boolean
This method returns false if no history filter has been created.
Example
The following example goes through the entire process of creating a filter, starting the query, obtaining and displaying the results, and canceling the query.
|
Sub
'-----------------SETUP------------------
' create the filter Dim bCreatedOk bCreatedOk = HistoryQuery.CreateHistoryFilter()
' check that the filter thread is running Dim bIsRunning bIsRunning = HistoryQuery.IsHistoryFilterRunning()
'-----------------EXECUTION------------------
' start filtering HistoryQuery.StartHistoryFiltering()
' wait for the thread to obtain history entries WScript.Sleep(1000)
Dim strTag strTag = "CYGDEMO.UIS.00002109:MYPOINTTAG"
Dim MyDateS MyDateS = "1/7/2010" Dim startDate startDate = CDate(MyDateS) Dim MyDateE MyDateE = "6/4/2010" Dim endDate endDate = CDate(MyDateE)
' retrieve a single history entry Dim pvHistoryInfoXml, bEntryRetrieved pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryAsXml(strTag, startDate, pvHistoryInfoXml) MsgBox pvHistoryInfoXml
' populate the internal set of entries for a given time window Dim nSize, bWindowRetrieved nSize = 0 bWindowRetrieved = HistoryQuery.GetHistoryEntriesWithinWindow(strTag, startDate, endDate, nSize)
' iterate through the set and retrieve each individual entry Dim iEntry For iEntry = 1 To nSize pvHistoryInfoXml = "" bEntryRetrieved = HistoryQuery.GetHistoryEntryFromWindowAsXml(iEntry, pvHistoryInfoXml) If bEntryRetrieved Then MsgBox pvHistoryInfoXml End if Next
'-----------------RESULTS------------------
' cancel the filtering, and wait 5 seconds for the thread to terminate HistoryQuery.CancelHistoryFiltering(5)
End Sub |
|
|
|
